What problem does this PR solve?

The remaining part of #4190 is the public drain API and the completion orchestration on top of the runtime layers from #4759, #4760, and #4761. This PR extracts that final layer so reviewers can focus on API semantics, single-session orchestration, and the remaining-work contract without re-reviewing the lower-level protocol and scheduler changes.

Issue Number: ref #4190

What is changed and how it works?

Background:

• This is PR 4/4 in the dispatcher-drain split stack and is based on coordinator,scheduler: add drain aware scheduling #4761.
• After maintainer,heartbeatpb: add drain target plumbing #4759, maintainer,scheduler: add dispatcher drain runtime #4760, and coordinator,scheduler: add drain aware scheduling #4761, the runtime can already propagate drain targets, evacuate dispatcher work, and avoid moving maintainers back to draining nodes.
• This PR only exposes the API and completion orchestration on top.

Motivation:

• Keep public API behavior out of the lower-level protocol and scheduler reviews.
• Enforce a single active drain session and avoid returning zero remaining before completion is proven.
• Keep drain target resend and clear-tombstone retry logic together with the API contract.

Summary:

• replace the current stub PUT /api/v1/captures/drain implementation with coordinator-backed drain requests
• add in-memory drainSession and drainClearState orchestration in coordinator
• keep broadcasting active drain targets and clear tombstones until all nodes observe the correct epoch
• aggregate maintainer drain progress and coordinator-side operator state before reporting remaining work
• extend coordinator interfaces and tests for the new drain orchestration path

How it works:

• the API validates the target and forwards the request to coordinator
• coordinator ensures a single active target epoch, requests node liveness drain, tracks progress convergence, and clears the target only after completion is proven
• heartbeat observation and node removal both feed the retry-based target and clear control loops

Validation note:

• the targeted drain API and coordinator tests below pass
• go test ./coordinator in the current environment still hits a fixed-port conflict because *:28300 is already occupied, but the targeted drain tests for this PR pass

Check List

Tests

• Unit test
  • go test ./api/v1 ./coordinator/operator ./pkg/server
  • go test -run 'TestDrain|TestDispatcherDrain|TestSetDrain|Test.*Drain' ./coordinator

Questions

Will it cause performance regression or break compatibility?

This PR intentionally changes the v1 drain endpoint from a stub to real coordinator-backed behavior. The implementation keeps the completion check conservative so the API does not return zero remaining until drain completion is proven.

Do you need to update user documentation, design documentation or monitoring documentation?

No additional design or monitoring document changes are needed for this split. The implementation follows the approved drain-capture split design and existing drain design docs.

Release note

Add coordinator-backed v1 capture drain orchestration with remaining-work reporting.